﻿/*****************************************************************************

   Project:   WP7AppLifecycleService
   File:      IWP7AppLifecycleService.cs 
   Creator:   David Carballo (dacarb@gmail.com)
   
   Description:
      Definition of IWP7AppLifecycleService interface.

   (C) Copyright 2011, David Carballo
       http://wp7applifecycle.codeplex.com/license


******************************************************************************/

namespace WP7AppLifecycleService
{
    /// <summary>
    /// IWP7AppLifecycleService is the main facade interface implemented by the service and that allows
    /// WP7 applications to register the different implementations of IApplicationStateHandler and
    /// IPageStateHandler.
    /// </summary>
    public interface IWP7AppLifecycleService
    {
        /// <summary>
        /// This event is raised when an application restart is required in order
        /// to for the idle detection mode to be active again after it has been
        /// disabled in the application (in order to get Locked/Unlocked) notifications.
        /// </summary>
        event System.EventHandler RestartRequiredAfterPhoneLockedHandlerUnregistered;

        /// <summary>
        /// Gets a value indicating whether the application is currently running in a locked phone
        /// </summary>
        bool IsRunningUnderLock
        {
            get;
        }

        /// <summary>
        /// Registers an <see cref="IApplicationStateHandler"/> instance, associating it to a specific 
        /// <see cref="Microsoft.Phone.Controls.PhoneApplicationPage"/> instance.
        /// </summary>
        /// <param name="page">The <see cref="Microsoft.Phone.Controls.PhoneApplicationPage"/> instance to associate the handler to.</param>
        /// <param name="handler">The <see cref="IApplicationStateHandler"/> instance that handles
        /// application state for the page.</param>
        /// <exception cref="System.ArgumentNullException">Either page or handler is a null reference (Nothing in Visual Basic).</exception>
        void RegisterApplicationStateHandler(Microsoft.Phone.Controls.PhoneApplicationPage page, IApplicationStateHandler handler);

        /// <summary>
        /// Registers an <see cref="IPageStateHandler"/> instance, associating it to a specific 
        /// <see cref="Microsoft.Phone.Controls.PhoneApplicationPage"/> instance.
        /// </summary>
        /// <param name="page">The <see cref="Microsoft.Phone.Controls.PhoneApplicationPage"/> instance to associate the handler to.</param>
        /// <param name="handler">The <see cref="IPageStateHandler"/> instance that handles
        /// page state for the page.</param>
        /// <exception cref="System.ArgumentNullException">Either page or handler is a null reference (Nothing in Visual Basic).</exception>
        void RegisterPageStateHandler(Microsoft.Phone.Controls.PhoneApplicationPage page, IPageStateHandler handler);

        /// <summary>
        /// Utility method provided that tells whether a given <see cref="Microsoft.Phone.Controls.PhoneApplicationPage"/> instance
        /// was tombstoned or not in case the application needs or wants to perform additional work.
        /// </summary>
        /// <param name="page">The <see cref="Microsoft.Phone.Controls.PhoneApplicationPage"/> instance to associate the handler to.</param>
        /// <returns>A boolean value indicating whether the given instance was tombstoned or not.</returns>
        /// <exception cref="System.ArgumentNullException">The page is a null reference (Nothing in Visual Basic).</exception>
        bool WasItTombstoned(Microsoft.Phone.Controls.PhoneApplicationPage page);

        /// <summary>
        /// Registers an <see cref="IPhoneLockedHandler"/> instance.
        /// </summary>
        /// <param name="handler">The <see cref="IPhoneLockedHandler"/> instance that handles
        /// when the phone is locked/unlocked.</param>
        /// <exception cref="System.ArgumentNullException">The handler is a null reference (Nothing in Visual Basic).</exception>
        void RegisterPhoneLockedHandler(IPhoneLockedHandler handler);

        /// <summary>
        /// Unregisters an <see cref="IPhoneLockedHandler"/> instance.
        /// </summary>
        /// <param name="handler">The <see cref="IPhoneLockedHandler"/> instance that handles
        /// when the phone is locked/unlocked.</param>
        /// <exception cref="System.ArgumentNullException">The handler is a null reference (Nothing in Visual Basic).</exception>
        void UnregisterPhoneLockedHandler(IPhoneLockedHandler handler);
    }
}